The Aptlantis Governance Framework: A Comprehensive Overview of Ecosystem Standards #### 1. Strategic Context: The Transition from Repositories to Ecosystems The Aptlantis development environment is undergoing a mandated strategic transition, moving from a collection of isolated repositories toward a strictly governed project ecosystem. This shift is designed to eliminate "architectural entropy"—the inevitable decay that occurs when project intent drifts and documentation fails to keep pace with code. By enforcing ecosystem-level standards, we ensure that projects do not become "graveyards of prototypes" but remain durable, high-signal assets that are recoverable and understandable years after active development ceases. This ecosystem is guided by a core Operating Philosophy that prioritizes systemic integrity: * Local-first by default: Tools must remain fully functional without reliance on hosted services. * Metadata matters: Every file, dataset, and command must explicitly carry its own context. * Operator-centered design: Development is driven by real-world workflow pain points, not abstract technical demos. * Context preservation: Documentation is treated as a preservation tool, ensuring rationale survives changes in maintainers or tooling. * Integrity is a feature: Hashes, manifests, and provenance records are treated as primary products of the development process. * Repeatability wins: Pipelines, schemas, and logs transform one-off manual efforts into durable, reusable systems. The conceptual foundation of this framework is established by three primary governance pillars, each defined by a "One-Sentence Philosophy": 1. Project Proposal Standard (PPS): "The proposal is the North Star; the boundaries are the guardrails." 2. Standard for Standards (SFDS): "The specification defines the rules. The examples demonstrate the rules. The validator proves the rules." 3. Desktop Release Standard (DRS): "The release note is the human promise. The manifest is the machine record. The hash binds them." This high-level governance is coordinated by the Workspace Governance Standard (WGS), which serves as the foundational "Constitution" for the entire ecosystem. -------------------------------------------------------------------------------- #### 2. Layer 1: The Constitutional Layer — Workspace Governance Standard (WGS) The Workspace Governance Standard (WGS) functions as the "Constitution" of Aptlantis. While other standards govern specific project behaviors, the WGS governs the environment itself. It mandates how projects are organized, registered, and tracked to ensure the workspace remains self-describing and discoverable. The WGS enforces a three-layer architecture to organize the ecosystem: * Standards Layer: Defines the behavioral rules (e.g., PPS, SFDS, DRS, CTS). This layer ensures that all "citizens" of the ecosystem adhere to a predictable lifecycle. * Projects Layer: The primary execution layer where artifacts (Desktop Apps, CLI Tools, Datasets, Websites) are produced according to their governing standards. * Shared Services Layer: Provides workspace-level infrastructure for all projects, located in centralized directories such as .agents (AI coordination), .data (registries), .docs (ecosystem documentation), .evals (quality reviews), and .sonar (static analysis). The WGS mandates that every project exists in exactly one state to enable effective portfolio prioritization: | State | Strategic Meaning | | ------ | ------ | | Concept | Initial high-level idea with defined scope. | | Planning | Active proposal and design work under PPS. | | Active | Project is under functional implementation. | | Feature Complete | Core functionality is finished; logic is stable. | | Release Prep | Final build verification and documentation pass. | | Released | Project is publicly stable and available. | | Maintenance | Sustained support and incremental updates. | | Paused | Intentionally inactive; context is frozen for future recovery. | | Archived | Historically preserved but no longer maintained. | | Superseded | Project has been replaced by a modern successor. | By standardizing these states, the WGS transforms the workspace from a folder of code into a managed portfolio, facilitating the birth of individual projects through the PPS. -------------------------------------------------------------------------------- #### 3. Layer 2: The Meta-Governance Layer — PPS and SFDS Reliability in the Aptlantis ecosystem is achieved by "front-loading intent." We mandate a "design boundary before code boundary" approach through the Project Proposal Standard (PPS) and the Standard for Standards (SFDS) . ##### Project Proposal Standard (PPS) The PPS enforces clarity by requiring a formal definition of a project's "Data Spine" and design constraints before implementation begins. This prevents mission creep and ensures that a project’s purpose is frozen in time. A PPS-compliant repository must include the following mandatory artifacts: * Project-Proposal.md: Narrative justification, problem statement, and mission. * Scope-Boundary.md: Explicit definition of non-goals (what the project will not do). * Success-Criteria.md: Outcome-based metrics for viability (e.g., "The user can relocate artifacts after one year"). * Roadmap.md: Phased progression from concept to release readiness. * Project-Manifest.toml: The machine-readable source of truth for portfolio analytics. ##### SFDS Maturity Model The SFDS ensures the governance layer itself remains consistent. It utilizes a five-tier maturity model to manage the evolution of standards: | Maturity Level | Strategic Intent | Required Artifacts | | ------ | ------ | ------ | | Level 0: Concept | Define scope and goals. | README, Scope, Goals, Non-goals. | | Level 1: Draft | Formalize specification. | Specification, Terminology, SemVer, Examples. | | Level 2: Candidate | Real-world testing. | Reference Implementation, Validation Rules. | | Level 3: Stable | Ready for adoption. | Changelog, Compatibility Guarantees, Adoption Guide. | | Level 4: Reference | Fully hardened. | Multiple Implementations, Standalone Validator. | This model ensures that only battle-tested logic becomes an ecosystem requirement, keeping projects recoverable even if their original authors depart. -------------------------------------------------------------------------------- #### 4. Layer 3: Domain-Specific Execution — DRS and CTS Once a project moves into implementation, it must conform to domain-specific standards. The distinction between the Desktop Release Standard (DRS) and the Command Tool Standard (CTS) reflects the different operational priorities of GUI versus CLI environments. ##### Desktop Application Release Standard (DRS) The DRS focuses on "shipping understanding" to ensure GUI tools like FileCabinet are maintainable. Core principles include: *  Ship understanding: A release must be self-explanatory to an outside operator. *  Every release has a theme: The work must match a pre-defined name to prevent scope drift. *  Artifact hash is the release: A release is invalid without a published SHA-256 or BLAKE3 hash. *  Detect before mutating: Systems must make state changes visible before they are executed. *  Documentation as a release blocker: Software is not ready if the manifest and release notes are incomplete. ##### Command Tool Standard (CTS) The CTS governs CLI utilities (e.g., ArchiveHasher ), prioritizing predictability and automation compatibility: 1. Text First: Tools must be fully functional without a graphical interface. 2. Machine-Readable Output: Every command must support JSON output via the --json flag. 3. Standardized Exit Codes: Tools must communicate state through documented codes (e.g., 0 for Success, 1 for General Failure). 4. Dry Run Capability: Destructive actions must be simulated via a --dry-run flag. ##### Release Blockers Comparison | DRS (Desktop) Release Blockers | CTS (CLI) Release Blockers | | ------ | ------ | | Installer build/launch failure. | Exit codes changed without documentation. | | Missing or inaccurate Release Notes. | JSON schema changed without a version bump. | | Manifest/Artifact hash mismatch. | Output cannot be parsed by documented tooling. | | UI/Theme inconsistencies (NeonInk). | Help output (--help) is inaccurate. | -------------------------------------------------------------------------------- #### 5. Layer 4: Technical & Specialized Standards — AAMHS, SESM, and NeonInk Technical standards provide the "technical glue" that binds integrity, metadata, and visual identity into a single machine-readable layer. ##### Specialized Standards Summary * Aptlantis Archive Multi-Hash Standard (AAMHS): Mandates the integrity layer for archival. It requires a parallel suite of 8 hashes (including SHA-256 and BLAKE3) to ensure verification diversity, utilizing PGP and post-quantum (SLH-DSA) signatures. * SVG Embedded Semantic Metadata (SESM): Transforms SVGs into "self-describing semantic capsules" by embedding a JSON block within the tag. This binds the AAMHS integrity hash directly to the visual asset. Key metadata fields include: * Asset: Role (e.g., logo, icon), title, and ecosystem tags. * Theme: Color tokens and visual modes. * LLM: Interpretation hints and natural language summaries for non-authoritative agent context. * Integrity: Hash values (BLAKE3/SHA-256) used to verify the file against the manifest. ##### NeonInk Design Language NeonInk is the design system that provides a semantic color palette, communicating system state through color rather than decoration: * Cyan/Teal: Navigation, focus, and structural elements. * Violet/Purple: Ingest, preview, and pipeline processing states. * Pink/Magenta: Featured items and metadata emphasis. * Green: Healthy, verified, and validated states. * Yellow: Attention-worthy or starred artifacts. * Orange: Large objects, build outputs, and installers. * Red: Failure, quarantine, or destructive actions. -------------------------------------------------------------------------------- #### 6. Synthesis: The Integrated Lifecycle and Ecosystem Relationships The "Aptlantis Project Operating System" creates a holistic flow that preserves context from the first proposal to long-term archival. ##### Layered Architecture Diagram markdown Workspace Governance Standard (WGS) [The Constitution] │ ├── Meta-Governance [Front-Loading Intent] │ ├── PPS (Project Proposals) │ └── SFDS (Standard for Standards) │ ├── Domain Execution [Rules of Engagement] │ ├── DRS (Desktop Apps) │ └── CTS (CLI Tools) │ └── Technical Glue [Integrity & Identity] ├── AAMHS (Archive Integrity / 8-Hash Suite) ├── SESM (Embedded Semantic Metadata) └── NeonInk (Semantic Design Language)  ##### The Agent Lifecycle To prevent "agent drift," all automated agents must follow a mandatory 6-step startup procedure: 1. Read Workspace Manifest: Understand the ecosystem context. 2. Read Project Manifest: Identify the project type and status. 3. Read PROJECT.md: Grasp the specific mission and design boundaries. 4. Read Governing Standard: (DRS, CTS, or SFDS) to understand the rules of the project class. 5. Read Roadmap: Identify the current phase of development. 6. Begin Work: Execute tasks within the established boundaries. ##### Project Genealogy and Intent Search By enforcing a machine-readable layer across all projects, the WGS enables Project Genealogy —the ability to map how projects relate (e.g., " FileCabinet implements DRS and utilizes NeonInk "). This enables Intent Search , allowing the architect or an agent to query the workspace for projects based on "archival goals" or "hashing requirements" rather than just code keywords. The ultimate goal of this framework is the total reduction of ambiguity, ensuring that the human rationale behind every technical decision is preserved as a durable, recoverable artifact.